<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc::session::Session&lt; Mdt_payload &gt; Class Template Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceipc.html">ipc</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1session.html">session</a></li><li class="navelem"><a class="el" href="classipc_1_1session_1_1Session.html">Session</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#pub-types">Public Types</a> &#124;
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="#pub-static-attribs">Static Public Attributes</a> &#124;
<a href="classipc_1_1session_1_1Session-members.html">List of all members</a>  </div>
  <div class="headertitle"><div class="title">ipc::session::Session&lt; Mdt_payload &gt; Class Template Reference</div></div>
</div><!--header-->
<div class="contents">

<p>A documentation-only <em>concept</em> defining the local side of an IPC conversation (<em>session</em>) with another entity (typically a separate process), also represented by a Session-implementing object, through which one can easily open IPC channels (<a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">ipc::transport::Channel</a>), among other IPC features.  
 <a href="classipc_1_1session_1_1Session.html#details">More...</a></p>

<p><code>#include &lt;<a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>&gt;</code></p>
<div class="dynheader">
Collaboration diagram for ipc::session::Session&lt; Mdt_payload &gt;:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1session_1_1Session__coll__graph.svg" width="246" height="131"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-types" name="pub-types"></a>
Public Types</h2></td></tr>
<tr class="memitem:a2f770785552536f3b929f293c44834d2"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">Channel_obj</a> = unspecified</td></tr>
<tr class="memdesc:a2f770785552536f3b929f293c44834d2"><td class="mdescLeft">&#160;</td><td class="mdescRight">Each successful <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> and on-passive-open handler firing shall yield a concrete <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a> instance of this type &ndash; in PEER state.  <a href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">More...</a><br /></td></tr>
<tr class="separator:a2f770785552536f3b929f293c44834d2"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:af572e522f2e85258bdfd091fd6e9a58b"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b">Mdt_payload_obj</a> = Mdt_payload</td></tr>
<tr class="memdesc:af572e522f2e85258bdfd091fd6e9a58b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Short-hand for <code>Mdt_payload</code> template arg.  <a href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b">More...</a><br /></td></tr>
<tr class="separator:af572e522f2e85258bdfd091fd6e9a58b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ac3f52804db8ecf1d0dc0d0bbdf97e062"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#ac3f52804db8ecf1d0dc0d0bbdf97e062">Mdt_builder</a> = typename transport::struc::schema::Metadata&lt; <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b">Mdt_payload_obj</a> &gt;<a class="el" href="classStruct__builder__config_1_1Builder.html">::Builder</a></td></tr>
<tr class="memdesc:ac3f52804db8ecf1d0dc0d0bbdf97e062"><td class="mdescLeft">&#160;</td><td class="mdescRight">Pointee of <a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b" title="Ref-counted handle to a capnp-generated Builder (and the payload it accesses) through which the user ...">Mdt_builder_ptr</a>.  <a href="classipc_1_1session_1_1Session.html#ac3f52804db8ecf1d0dc0d0bbdf97e062">More...</a><br /></td></tr>
<tr class="separator:ac3f52804db8ecf1d0dc0d0bbdf97e062"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a2ee877327fded2c2b1978453831c2b1b"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b">Mdt_builder_ptr</a> = shared_ptr&lt; <a class="el" href="classipc_1_1session_1_1Session.html#ac3f52804db8ecf1d0dc0d0bbdf97e062">Mdt_builder</a> &gt;</td></tr>
<tr class="memdesc:a2ee877327fded2c2b1978453831c2b1b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Ref-counted handle to a capnp-generated <code>Builder</code> (and the payload it accesses) through which the user shall mutate the <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> metadata before invoking <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>.  <a href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b">More...</a><br /></td></tr>
<tr class="separator:a2ee877327fded2c2b1978453831c2b1b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae197d051e06be6f132e193e9ba7ab6ae"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#ae197d051e06be6f132e193e9ba7ab6ae">Mdt_reader_ptr</a> = shared_ptr&lt; typename transport::struc::schema::Metadata&lt; <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b">Mdt_payload_obj</a> &gt;::Reader &gt;</td></tr>
<tr class="memdesc:ae197d051e06be6f132e193e9ba7ab6ae"><td class="mdescLeft">&#160;</td><td class="mdescRight">Ref-counted handle to a capnp-generated <code>Reader</code> (and the payload it accesses) through which the user shall access the metadata the other side prepared via <a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b" title="Ref-counted handle to a capnp-generated Builder (and the payload it accesses) through which the user ...">Mdt_builder_ptr</a>.  <a href="classipc_1_1session_1_1Session.html#ae197d051e06be6f132e193e9ba7ab6ae">More...</a><br /></td></tr>
<tr class="separator:ae197d051e06be6f132e193e9ba7ab6ae"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a29eaaa691a992e3a83662e00be7d7446"><td class="memTemplParams" colspan="2">template&lt;typename Message_body &gt; </td></tr>
<tr class="memitem:a29eaaa691a992e3a83662e00be7d7446"><td class="memTemplItemLeft" align="right" valign="top">using&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a29eaaa691a992e3a83662e00be7d7446">Structured_channel</a> = <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html">transport::struc::Channel</a>&lt; unspecified &gt;</td></tr>
<tr class="memdesc:a29eaaa691a992e3a83662e00be7d7446"><td class="mdescLeft">&#160;</td><td class="mdescRight">Convenience alias for the <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a> concrete type to use if one desires (1) to upgrade a <code>*this</code>-generated channel to a <code>struc::Channel</code> and (2) to efficiently use the built-in capabilities of <code>*this</code> (notably, if applicable: SHM) for zero-copy performance when sending messages through that channel.  <a href="classipc_1_1session_1_1Session.html#a29eaaa691a992e3a83662e00be7d7446">More...</a><br /></td></tr>
<tr class="separator:a29eaaa691a992e3a83662e00be7d7446"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a2612cefeace1ba12e649ba0e509aaab1"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a2612cefeace1ba12e649ba0e509aaab1">Structured_msg_builder_config</a> = unspecified</td></tr>
<tr class="memdesc:a2612cefeace1ba12e649ba0e509aaab1"><td class="mdescLeft">&#160;</td><td class="mdescRight">Convenience alias equal to <code>Structured_channel&lt;M&gt;::Builder_config</code> (regardless of <code>M</code>).  <a href="classipc_1_1session_1_1Session.html#a2612cefeace1ba12e649ba0e509aaab1">More...</a><br /></td></tr>
<tr class="separator:a2612cefeace1ba12e649ba0e509aaab1"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ac23d047087984addf221f0baa0058616"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#ac23d047087984addf221f0baa0058616">Structured_msg_reader_config</a> = unspecified</td></tr>
<tr class="memdesc:ac23d047087984addf221f0baa0058616"><td class="mdescLeft">&#160;</td><td class="mdescRight">Convenience alias equal to <code>Structured_channel&lt;M&gt;::Reader_config</code> (regardless of <code>M</code>).  <a href="classipc_1_1session_1_1Session.html#ac23d047087984addf221f0baa0058616">More...</a><br /></td></tr>
<tr class="separator:ac23d047087984addf221f0baa0058616"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a08416c5a34aa4eb58db094e946b540e3"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a08416c5a34aa4eb58db094e946b540e3">Session</a> ()</td></tr>
<tr class="memdesc:a08416c5a34aa4eb58db094e946b540e3"><td class="mdescLeft">&#160;</td><td class="mdescRight">Default ctor: creates <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> in NULL state (not operational).  <a href="classipc_1_1session_1_1Session.html#a08416c5a34aa4eb58db094e946b540e3">More...</a><br /></td></tr>
<tr class="separator:a08416c5a34aa4eb58db094e946b540e3"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a230afdc0889f869e3b0606a826115745"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a230afdc0889f869e3b0606a826115745">Session</a> (<a class="el" href="classipc_1_1session_1_1Session.html">Session</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:a230afdc0889f869e3b0606a826115745"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move ctor: <code>*this</code> becomes identical to <code>src</code>; while <code>src</code> becomes as-if default-cted.  <a href="classipc_1_1session_1_1Session.html#a230afdc0889f869e3b0606a826115745">More...</a><br /></td></tr>
<tr class="separator:a230afdc0889f869e3b0606a826115745"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a611bf472626baa35d3e6cd661735d953"><td class="memItemLeft" align="right" valign="top"><a id="a611bf472626baa35d3e6cd661735d953" name="a611bf472626baa35d3e6cd661735d953"></a>
&#160;</td><td class="memItemRight" valign="bottom"><b>Session</b> (const <a class="el" href="classipc_1_1session_1_1Session.html">Session</a> &amp;)=delete</td></tr>
<tr class="memdesc:a611bf472626baa35d3e6cd661735d953"><td class="mdescLeft">&#160;</td><td class="mdescRight">Copy construction is disallowed. <br /></td></tr>
<tr class="separator:a611bf472626baa35d3e6cd661735d953"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8cb20f446c2a4327a3a8143af137dbca"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a8cb20f446c2a4327a3a8143af137dbca">~Session</a> ()</td></tr>
<tr class="memdesc:a8cb20f446c2a4327a3a8143af137dbca"><td class="mdescLeft">&#160;</td><td class="mdescRight">In NULL state, no-op; in PEER state: Ends the session while informing (if possible) the opposing peer <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> that the present session has ended.  <a href="classipc_1_1session_1_1Session.html#a8cb20f446c2a4327a3a8143af137dbca">More...</a><br /></td></tr>
<tr class="separator:a8cb20f446c2a4327a3a8143af137dbca"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa3e921f8f06a051423c60ba2f2736dde"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1session_1_1Session.html">Session</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#aa3e921f8f06a051423c60ba2f2736dde">operator=</a> (<a class="el" href="classipc_1_1session_1_1Session.html">Session</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:aa3e921f8f06a051423c60ba2f2736dde"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move assignment: acts as-if <code>*this</code> dtor executed; then <code>*this</code> becomes identical to <code>src</code>; while <code>src</code> becomes as-if default-cted.  <a href="classipc_1_1session_1_1Session.html#aa3e921f8f06a051423c60ba2f2736dde">More...</a><br /></td></tr>
<tr class="separator:aa3e921f8f06a051423c60ba2f2736dde"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aee51c401ffff7cc66787c566d734f8e3"><td class="memItemLeft" align="right" valign="top"><a id="aee51c401ffff7cc66787c566d734f8e3" name="aee51c401ffff7cc66787c566d734f8e3"></a>
<a class="el" href="classipc_1_1session_1_1Session.html">Session</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><b>operator=</b> (const <a class="el" href="classipc_1_1session_1_1Session.html">Session</a> &amp;)=delete</td></tr>
<tr class="memdesc:aee51c401ffff7cc66787c566d734f8e3"><td class="mdescLeft">&#160;</td><td class="mdescRight">Copy assignment is disallowed. <br /></td></tr>
<tr class="separator:aee51c401ffff7cc66787c566d734f8e3"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a420df732069ded1feef423adf7a30915"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b">Mdt_builder_ptr</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a420df732069ded1feef423adf7a30915">mdt_builder</a> ()</td></tr>
<tr class="memdesc:a420df732069ded1feef423adf7a30915"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns a new metadata holder to be subsequently mutated by the user and then passed to <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> to initiate active-open attempt.  <a href="classipc_1_1session_1_1Session.html#a420df732069ded1feef423adf7a30915">More...</a><br /></td></tr>
<tr class="separator:a420df732069ded1feef423adf7a30915"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aab01aefa0243abf84c7cc36d3ab2d852"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852">open_channel</a> (<a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">Channel_obj</a> *target_channel, const <a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b">Mdt_builder_ptr</a> &amp;mdt, <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0)</td></tr>
<tr class="memdesc:aab01aefa0243abf84c7cc36d3ab2d852"><td class="mdescLeft">&#160;</td><td class="mdescRight">Synchronously active-opens a new channel which, on success, is moved-to <code>*target_channel</code>.  <a href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852">More...</a><br /></td></tr>
<tr class="separator:aab01aefa0243abf84c7cc36d3ab2d852"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:afd8c8f5e2c71c2c4c58f77f134aa076c"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#afd8c8f5e2c71c2c4c58f77f134aa076c">open_channel</a> (<a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">Channel_obj</a> *target_channel, <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0)</td></tr>
<tr class="memdesc:afd8c8f5e2c71c2c4c58f77f134aa076c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Identical to <code>open_channel(target_channel, mdt_builder(), err_code)</code>; in other words attempts to open channel with an uninitialized channel-open metadata payload.  <a href="classipc_1_1session_1_1Session.html#afd8c8f5e2c71c2c4c58f77f134aa076c">More...</a><br /></td></tr>
<tr class="separator:afd8c8f5e2c71c2c4c58f77f134aa076c"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:abc6ce8839621c1e19db80ccd4f2e2589"><td class="memItemLeft" align="right" valign="top">const <a class="el" href="namespaceipc_1_1session.html#ade2b302f1a3623e8adc9694568d94d2c">Session_token</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#abc6ce8839621c1e19db80ccd4f2e2589">session_token</a> () const</td></tr>
<tr class="memdesc:abc6ce8839621c1e19db80ccd4f2e2589"><td class="mdescLeft">&#160;</td><td class="mdescRight">In PEER state: Returns the (non-nil) logged-in session token to be used for any <code>struc::Channel</code>s one may wish to upgrade from <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a> channels yielded by <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> or passive-opens; or nil if in NULL state, or if <code>*this</code> session is hosed from a prior error.  <a href="classipc_1_1session_1_1Session.html#abc6ce8839621c1e19db80ccd4f2e2589">More...</a><br /></td></tr>
<tr class="separator:abc6ce8839621c1e19db80ccd4f2e2589"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-static-attribs" name="pub-static-attribs"></a>
Static Public Attributes</h2></td></tr>
<tr class="memitem:a62a1a415a92bf6e0b4d83987394ae78b"><td class="memItemLeft" align="right" valign="top">static constexpr schema::ShmType&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a62a1a415a92bf6e0b4d83987394ae78b">S_SHM_TYPE</a> = unspecified</td></tr>
<tr class="memdesc:a62a1a415a92bf6e0b4d83987394ae78b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Specifies the SHM-provider for which this <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> concept implementation provides support; or <code>NONE</code> if this is a vanilla <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> that does not provide SHM-based zero-copy support.  <a href="classipc_1_1session_1_1Session.html#a62a1a415a92bf6e0b4d83987394ae78b">More...</a><br /></td></tr>
<tr class="separator:a62a1a415a92bf6e0b4d83987394ae78b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a7f28ff5d2fc6e9830877979fafe48cf7"><td class="memItemLeft" align="right" valign="top">static constexpr bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1session_1_1Session.html#a7f28ff5d2fc6e9830877979fafe48cf7">S_SHM_ENABLED</a> = unspecified</td></tr>
<tr class="memdesc:a7f28ff5d2fc6e9830877979fafe48cf7"><td class="mdescLeft">&#160;</td><td class="mdescRight">Specifies whether this <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> concept implementation provides support for zero-copy via SHM plus direct access to SHM arenas and lending/borrowing within them.  <a href="classipc_1_1session_1_1Session.html#a7f28ff5d2fc6e9830877979fafe48cf7">More...</a><br /></td></tr>
<tr class="separator:a7f28ff5d2fc6e9830877979fafe48cf7"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><div class="compoundTemplParams">template&lt;typename Mdt_payload = ::capnp::Void&gt;<br />
class ipc::session::Session&lt; Mdt_payload &gt;</div><p >A documentation-only <em>concept</em> defining the local side of an IPC conversation (<em>session</em>) with another entity (typically a separate process), also represented by a Session-implementing object, through which one can easily open IPC channels (<a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">ipc::transport::Channel</a>), among other IPC features. </p>
<p >While it is possible to open a <code>Channel</code> without the help of this <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> concept, for many users writing large multi-channel applications it would be too laborious to do so. The <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> concept is the central one in <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> doc header. </dd>
<dd>
<a class="el" href="classipc_1_1session_1_1Session__mv.html" title="Implements the Session concept when it is in PEER state.">Session_mv</a> which implements the majority of <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> concept, namely when it is in PEER state.</dd></dl>
<h3>Concept contents</h3>
<p >The concept defines the following behaviors/requirements.</p><ul>
<li>The object has at least 2 states:<ul>
<li>NULL: Object is not a peer: is not open/capable of operation. Essentially it is not a useful state. A default-cted object is in NULL state; and a moved-from object is as-if default-cted, therefore also in a NULL state. In this state all the transmission-related methods return <code>false</code>/sentinel and no-op.</li>
<li>PEER: Object is or has been a peer (open/capable of operation). It is not possible to exit PEER state, except via being moved-from. The session ending, such as due to the partner process exiting, retains PEER state for instance.</li>
<li>Other states are allowed but outside the scope of the concept. For example a CONNECTING state may or may not be relevant (but again not relevant to this concept).</li>
</ul>
</li>
<li>Active-opening a channel: <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>. See its doc header. It yields a PEER-state <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a>.</li>
<li>Passive-opening a channel (the counterpart to the partner <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a>'s <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>).<ul>
<li>At entry to PEER state (the mechanism of accomplishing which, as noted below, is not specified by the concept) the user must have provided a passive-open handler (discussed below in detail) via which subsequent passive-opens are reported to the user. To this handler a PEER-state <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a> is passed in case of success.</li>
<li>Alternatively, if at entry to PEER state the user has chosen to <em>not</em> supply a passive-open handler, then the partner <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">Session::open_channel()</a> shall yield failure. In this mode of operation, the user has chosen this side of the session to not act as a passive-opener. (If both <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code>s do so, the session is essentially useless. Formally this is supported, simply because there is no need to enforce otherwise.)</li>
</ul>
</li>
<li>Async error reporting: At entry to PEER state (the mechanism of accomplishing which, as noted below, is not specified by the concept) the user must have provided an on-error handler via which asynchronously-occurring session-hosing <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> are reported. See details below.</li>
<li>The (outgoing) transmission-of-messages methods, including transmission of graceful-close message. See their doc headers.</li>
<li>Behavior when the destructor is invoked. See <a class="el" href="classipc_1_1session_1_1Session.html#a8cb20f446c2a4327a3a8143af137dbca" title="In NULL state, no-op; in PEER state: Ends the session while informing (if possible) the opposing peer...">~Session()</a> doc header.</li>
<li>Default ctor (which creates a NULL-state object that can be moved-to and to which "as-if" state any moved-from object is changed).</li>
<li>Move ctor, move assigment operator; these do the reasonable thing including setting the moved-from object to NULL state. Various satellite APIs (e.g., <a class="el" href="classipc_1_1session_1_1Session__server.html" title="To be instantiated typically once in a given process, an object of this type asynchronously listens f...">Session_server</a>) may need these. That is such APIs do not rely on the factory/shared-ownership pattern.</li>
</ul>
<p >The concept (intentionally) does <em>not</em> define the following behaviors:</p><ul>
<li>How to create a <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a>, except the default and move ctors. That is it does not define how to create a <em>new</em> (not moved-from) and <em>functioning</em> (PEER state: open/capable of communication) peer object. It only defines behavior once the user has access to a <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> that is already in PEER state: connected to an opposing peer <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a>.</li>
</ul>
<h3>Async-I/O channels versus <code><a class="el" href="namespaceipc_1_1session_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::session.">sync_io</a></code> ones</h3>
<p >There are 3, overall, ways to obtain a <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a> via <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>.</p><ul>
<li><a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">Session::open_channel()</a>. It's a synchronous operation; it sets a <code>Channel</code> as a pointer out-arg.</li>
<li>Passive-opening. It's an async operation via passive-open handler (see below for details).</li>
<li>Init-channels. <a class="el" href="classipc_1_1session_1_1Client__session__mv.html#ab971ea979200828d572638c60d7d9f44" title="To be invoked in NULL state only, and not as-if default-cted, it synchronously and non-blockingly att...">Client_session_mv::sync_connect()</a> (et al) and <a class="el" href="classipc_1_1session_1_1Session__server.html#a13887cd64912bb5f5675e2817ff8435f" title="Asynchronously awaits for an opposing Client_session to request session establishment and calls on_do...">Session_server::async_accept()</a> (et al) provide ways to pre-open channels to be ready the moment the session enters PEER state.</li>
</ul>
<p >In all cases these channels shall bear <code><a class="el" href="namespaceipc_1_1session_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::session.">sync_io</a></code>-pattern peer objects: not async-I/O ones.</p><ul>
<li>They are lighter-weight to create and pass around.</li>
<li>They can be immediately fed to <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a> or <a class="el" href="classipc_1_1transport_1_1struc_1_1sync__io_1_1Channel.html" title="sync_io-pattern counterpart to async-I/O-pattern transport::struc::Channel.">transport::struc::sync_io::Channel</a> ctor via <code>move()</code> semantics.</li>
<li>They can be trivially upgraded to async-I/O form via <a class="el" href="classipc_1_1transport_1_1Channel.html#add016cbac936d3da6c861755ac88b7a2" title="Converts a sync_io-peer-bearing *this to a returned async-I/O-peer-bearing new Channel,...">transport::Channel::async_io_obj()</a>.</li>
</ul>
<h3>Thread safety and handler invocation semantics</h3>
<p >As is typical: 2 different <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> objects are safe to invoke methods on concurrently; it is not safe to invoke a non-<code>const</code> method on a given <code>*this</code> concurrently to any other method on the same <code>*this</code>.</p>
<p >The handlers &ndash; namely the passive-open handler (optional) and the on-error handler (mandatory) &ndash; shall be invoked from some unspecified thread that is not any one of the user's calling threads. It is <em>not</em> allowed to invoke <code>*this</code> APIs from within any such handler. For example, you may not <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> from the passive-open handler. Informally, it is recommended that any user handler post its actual handling of the event onto their own thread(s), such as via <code>flow::async::Single_thread_task_loop::post()</code>.</p>
<h3>Passive-open handler semantics</h3>
<p >As summarized above, a <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> &ndash; at entry to PEER state &ndash; is optionally capable of accepting the partner <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a>'s active-open (<a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>) attempt. The user must make the decision whether to be capable or incapable of performing such a passive-open. If they decide the latter, they must not set the <em>on-passive-open</em> handler; else they must set it by the time PEER state begins. (The mechanism of doing so is unspecified by the concept. The current impls, <a class="el" href="namespaceipc_1_1session.html#ab01d5bce0ab2f3435ca9dd88d27609dc" title="A vanilla Server_session with no optional capabilities.">Server_session</a> and <a class="el" href="namespaceipc_1_1session.html#a77d8fda00e1e17f595a6a5d4c44375e7" title="A vanilla Client_session with no optional capabilities.">Client_session</a>, use different APIs for this.)</p>
<p >If the choice is made to indeed perform passive-opens (accept other side's active-opens), then suppose the handler H is indeed saved inside <code>*this</code> (which is in PEER state). Then the following shall be invoked from some unspecified thread that is not one of the user's public API-invoking threads: <code>H(C, M)</code>, where <code>C</code> is a <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a> onto which the new PEER-state <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a> shall be <code>move()</code>d; while <code>M</code> is the metadata reader (explained below). Therefore the H signature must be compatible with:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> H(<a class="code hl_typedef" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">Channel_obj</a>&amp;&amp; new_peer_channel, <a class="code hl_typedef" href="classipc_1_1session_1_1Session.html#ae197d051e06be6f132e193e9ba7ab6ae">Mdt_reader_ptr</a>&amp;&amp; metadata_reader)</div>
<div class="ttc" id="aclassipc_1_1session_1_1Session_html_a2f770785552536f3b929f293c44834d2"><div class="ttname"><a href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">ipc::session::Session::Channel_obj</a></div><div class="ttdeci">unspecified Channel_obj</div><div class="ttdoc">Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00235">session.hpp:235</a></div></div>
<div class="ttc" id="aclassipc_1_1session_1_1Session_html_ae197d051e06be6f132e193e9ba7ab6ae"><div class="ttname"><a href="classipc_1_1session_1_1Session.html#ae197d051e06be6f132e193e9ba7ab6ae">ipc::session::Session::Mdt_reader_ptr</a></div><div class="ttdeci">shared_ptr&lt; typename transport::struc::schema::Metadata&lt; Mdt_payload_obj &gt;::Reader &gt; Mdt_reader_ptr</div><div class="ttdoc">Ref-counted handle to a capnp-generated Reader (and the payload it accesses) through which the user s...</div><div class="ttdef"><b>Definition:</b> <a href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00261">session.hpp:262</a></div></div>
</div><!-- fragment --><p >Note that <a class="el" href="classipc_1_1session_1_1Session.html#ae197d051e06be6f132e193e9ba7ab6ae" title="Ref-counted handle to a capnp-generated Reader (and the payload it accesses) through which the user s...">Mdt_reader_ptr</a> is a <code>shared_ptr</code> to a capnp-generated <code>Reader</code> to a capnp-<code>struct</code> parameterized on <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b" title="Short-hand for Mdt_payload template arg.">Mdt_payload_obj</a>. The memory resources taken by the serialization of the metadata (including certain internal zero-copy "baggage") shall be freed once that <code>shared_ptr</code> ref-count group is empty. As for what the heck this even <em>is</em>: see <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>'s metadata arg docs. This is the <code>Reader</code> counterpart to the <code>Builder</code> mutated by the opposing <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> caller.</p>
<h3>Open channel metadata</h3>
<p ><a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> is used to initiate a channel opening on one side, and the on-passive-open handler is used to accept the same on the other side (for a given channel). The result, on each side, is a <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a>, which is a <code>Channel</code> template instantiation. Note that it is not a <code>struc::Channel</code>; the user may choose to immediate convert <code>Channel</code> to <code>struc::Channel</code> via std::move(), but whether they want to or not is up to them and their desired use case. Now, there are millions of patterns of what the acceptor might want to accept in a session; there could be one channel for some app-wide updates and one per processor core; and possibly more differentiation than that regarding which channel is for what purpose. Meanwhile the only way to know which channel is being opened, other than a set ordering (certainly inconvenient at best in many cases), is to perhaps exchange some information on the channels themselves. That too is inconvenient: even having discovered that a certain channel is for a certain purpose, distributing them around the app is no fun probably. Furthermore, it's only a <code>Channel</code>: is the user supposed to encode something in a binary blob? Inconvenient. But if one turns it into a <code>struc::Channel</code>, then that is irreversible and may not be what the user wants. The solution we use: the <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> call is issued with a separate (to any structured in-message the user would see) chunk of capnp-structured <em>metadata</em>. This is transmitted and supplied to the on-passive-open handler per the preceding doc section. Details:</p>
<p >It is encoded in a capnp-<code>struct</code> <code>Metadata</code>, defined in common.capnp. However that <code>struct</code> is generically parameterized on another capnp-type of the user's choice. That is the <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> template arg <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b" title="Short-hand for Mdt_payload template arg.">Mdt_payload_obj</a>. Hence the user shall decide how to encode the channel-differentiating info on a per-Session basis. capnp shall generate the usual <code>Reader</code> and <code>Builder</code> nested classes; the latter to build it to pass into <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>; the former to read it, the on-passive-open handler having fired. Call capnp-generated <code>Builder</code> setters and <code>Reader</code> getters accordingly on either side.</p>
<p >This feature is optional to use. You may set <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b" title="Short-hand for Mdt_payload template arg.">Mdt_payload_obj</a> to <code>capnp::Void</code>; omit the metadata argument to <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>; and ignore the <code>Reader</code> counterpart in the on-passive-open handler.</p>
<p >Informal suggestion: While <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> concept does not specify anything about clients or servers, as of this writing the client-server model is the only one available, hence <a class="el" href="namespaceipc_1_1session.html#a77d8fda00e1e17f595a6a5d4c44375e7" title="A vanilla Client_session with no optional capabilities.">Client_session</a> and <a class="el" href="namespaceipc_1_1session.html#ab01d5bce0ab2f3435ca9dd88d27609dc" title="A vanilla Server_session with no optional capabilities.">Server_session</a> are the impls used. <code>Server_session</code>s are produced, in this model, via <a class="el" href="classipc_1_1session_1_1Session__server.html" title="To be instantiated typically once in a given process, an object of this type asynchronously listens f...">Session_server</a>. The latter class template requires that <code>Mdt_payload</code> be specified as a template arg to be applied to all Server_session objects it produces. Therefore it must be decided not just for each session but realistically for the entire client/server split (in other words the entire meta-application that was split into two): all the <code>Server_session</code>s; and therefore to all the <code>Client_session</code>s as well (since the 2 are peers to each other). So the method of signaling channel type (if needed) via metadata is quite a high-level decision. One obvious idea is to maintain a split-wide capnp schema that specifies the <code>struct</code> to use as <code>Mdt_payload</code>; in that <code>struct</code> define perhaps a capnp-<code>enum</code> type for channel type. Alternatively one can define a top-level anon capnp-<code>union</code>; its <code>which()</code> selector can function as an enumeration (in fact it is one in the generated C++); and any further data (e.g., the processor core index, if there's some channel-per-core setup) inside that particular <code>which()</code>'s <code>struct</code>. Do be careful to (1) maintain backward and forward compatibility as channel types are added over time; and (2) do not abuse the metadata store with large structures. Anything that is not directly used in differentiating between channels should simply be communicated over the channel itself, once it has been routed to the proper area of code; that's what <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a> is for in particular.</p>
<h3>Error handling semantics</h3>
<p >There are 2 sources of errors: background (async) errors and synchronously from invoking active-open: <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>. A given error is either <em>session-hosing</em> (fatal) or not. To make handling error simpler these are the semantics:</p><ul>
<li><a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> synchronously emitted errors: <em>not</em> session-hosing.</li>
<li>Background (async) errors: <em>always</em> session-hosing.</li>
</ul>
<p >Even if, internally, <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> in some way triggers a session-hosing error, it shall be emitted as-if it were an async error in a way indistinguishable in practice from any other async error.</p>
<p >When a session-hosing error occurs, it is emitted exactly once (through the on-error handler). After such an event, <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> and other APIs shall no-op/return sentinel subsequently if invoked.</p>
<p >This is simpler than how <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a> emits errors; there the (always synchronous) <code>send()</code> can emit an error synchronously that is session-hosing; in addition to incoming-direction session-hosing errors; but still only one of these can occur and only once. So in that sense <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> is <em>not</em> like <code>send()</code>: if it emits an error, <code>*this</code> is still formally in non-session-hosed state.</p>
<p >However, of course, the user is free to treat an <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>-emitted error as fatal and destroy <code>*this</code>.</p>
<dl class="section see"><dt>See also</dt><dd>Channel and buddies: the main object of opening a <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> is to be able to easily active-open and/or passive-open <code>Channel</code>s in PEER state through it. </dd>
<dd>
<a class="el" href="namespaceipc_1_1session.html#a77d8fda00e1e17f595a6a5d4c44375e7" title="A vanilla Client_session with no optional capabilities.">Client_session</a>, <a class="el" href="namespaceipc_1_1session.html#ab01d5bce0ab2f3435ca9dd88d27609dc" title="A vanilla Server_session with no optional capabilities.">Server_session</a>: as of this writing, any non-SHM-enabled pair of PEER-state <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code>s is a <a class="el" href="namespaceipc_1_1session.html#a77d8fda00e1e17f595a6a5d4c44375e7" title="A vanilla Client_session with no optional capabilities.">Client_session</a> and a <a class="el" href="namespaceipc_1_1session.html#ab01d5bce0ab2f3435ca9dd88d27609dc" title="A vanilla Server_session with no optional capabilities.">Server_session</a>. <code><a class="el" href="namespaceipc_1_1session.html#ab01d5bce0ab2f3435ca9dd88d27609dc" title="A vanilla Server_session with no optional capabilities.">Server_session</a></code>s in a process, designated as the <em>server</em> in an IPC <em>split</em>, are obtained (following the acceptor pattern) via a single <a class="el" href="classipc_1_1session_1_1Session__server.html" title="To be instantiated typically once in a given process, an object of this type asynchronously listens f...">Session_server</a> in that process. On the other side, a <a class="el" href="namespaceipc_1_1session.html#a77d8fda00e1e17f595a6a5d4c44375e7" title="A vanilla Client_session with no optional capabilities.">Client_session</a> is directly constructed (in NULL state) and enters PEER state via <a class="el" href="classipc_1_1session_1_1Client__session__mv.html#ab971ea979200828d572638c60d7d9f44" title="To be invoked in NULL state only, and not as-if default-cted, it synchronously and non-blockingly att...">Client_session::sync_connect()</a>. (Conceptually this is similar to the relationship between, e.g., Native_socket_stream (server side), Native_socket_stream_acceptor, and Native_socket_stream (client side). However, it so happens that in the case of <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code>s, a different class is used depending on which side the <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> sits. Since they both implement the same concept, however, code can be written that behaves identically &ndash; given any <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> in PEER state &ndash; regardless of whether it's really a <a class="el" href="namespaceipc_1_1session.html#a77d8fda00e1e17f595a6a5d4c44375e7" title="A vanilla Client_session with no optional capabilities.">Client_session</a> or <a class="el" href="namespaceipc_1_1session.html#ab01d5bce0ab2f3435ca9dd88d27609dc" title="A vanilla Server_session with no optional capabilities.">Server_session</a>. That said, such code does have to be templated on the particular <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> as a template param.) </dd>
<dd>
E.g., <a class="el" href="namespaceipc_1_1session_1_1shm_1_1classic.html#ac6c443a72e0f22710c83bb1e8c229618" title="This is to session::Client_session what shm::classic::Server_session is to session::Server_session.">shm::classic::Client_session</a> and <a class="el" href="classipc_1_1session_1_1shm_1_1classic_1_1Server__session.html" title="Identical to session::Server_session in every way, except that it makes available two SHM arenas,...">shm::classic::Server_session</a> which are an example of a SHM-enabled variant of <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> impls.</dd></dl>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">Mdt_payload</td><td>capnp-generated class for the user's capnp-<code>struct</code> of choice for <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> transmitting metadata information to be received on the other side's on-passive-open handler. See discussion above. Use <code>capnp::Void</code> if not planning to use this metadata feature. </td></tr>
  </table>
  </dd>
</dl>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00215">215</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>
</div><h2 class="groupheader">Member Typedef Documentation</h2>
<a id="a2f770785552536f3b929f293c44834d2" name="a2f770785552536f3b929f293c44834d2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2f770785552536f3b929f293c44834d2">&#9670;&nbsp;</a></span>Channel_obj</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Channel_obj =  unspecified</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Each successful <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> and on-passive-open handler firing shall yield a concrete <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a> instance of this type &ndash; in PEER state. </p>
<p >The concept does not specify how the concrete Channel instance type &ndash; meaning the template params to <code>Channel</code> &ndash; is determined. In practice it is likely to be controlled by unspecified compile-time knobs, likely additional template params, to the particular <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> impl. E.g., see Client_session:S_MQS_ENABLED.</p>
<p >In practice a user is likely to declare <code>Channel</code> variables by using this alias (or via <code>auto</code>).</p>
<dl class="section note"><dt>Note</dt><dd><a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a> shall be such that its compile-time <a class="el" href="classipc_1_1transport_1_1Channel.html#ae5be240d29389d7b728950e85df0704e" title="Useful for generic programming: true &lt;=&gt; each non-Null_peer peer type (Blob_sender_obj,...">transport::Channel::S_IS_SYNC_IO_OBJ</a> is <code>true</code>. E.g., if it's got a native-socket-stream, it'll be <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream.html" title="Implements both sync_io::Native_handle_sender and sync_io::Native_handle_receiver concepts by using a...">transport::sync_io::Native_socket_stream</a> &ndash; not <a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html" title="Implements both Native_handle_sender and Native_handle_receiver concepts by using a stream-oriented U...">transport::Native_socket_stream</a>. If you want one with <a class="el" href="classipc_1_1transport_1_1Channel.html#a9f75b20b07eff47a69c2b1dbe5c85f84" title="It equals the reverse of S_IS_SYNC_IO_OBJ.">transport::Channel::S_IS_ASYNC_IO_OBJ</a> then use <a class="el" href="classipc_1_1transport_1_1Channel.html#add016cbac936d3da6c861755ac88b7a2" title="Converts a sync_io-peer-bearing *this to a returned async-I/O-peer-bearing new Channel,...">transport::Channel::async_io_obj()</a> (or to just get the type at compile time: <a class="el" href="classipc_1_1transport_1_1Channel.html#ab6f7d14037e228e24a8fbd33b41e1c82" title="Assuming S_IS_SYNC_IO_OBJ yields async-I/O counterpart; else yields Channel&lt;Null_peer,...">transport::Channel::Async_io_obj</a>). </dd></dl>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00235">235</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="ac3f52804db8ecf1d0dc0d0bbdf97e062" name="ac3f52804db8ecf1d0dc0d0bbdf97e062"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac3f52804db8ecf1d0dc0d0bbdf97e062">&#9670;&nbsp;</a></span>Mdt_builder</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Mdt_builder =  typename transport::struc::schema::Metadata&lt;<a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b">Mdt_payload_obj</a>&gt;<a class="el" href="classStruct__builder__config_1_1Builder.html">::Builder</a></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Pointee of <a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b" title="Ref-counted handle to a capnp-generated Builder (and the payload it accesses) through which the user ...">Mdt_builder_ptr</a>. </p>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00241">241</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="a2ee877327fded2c2b1978453831c2b1b" name="a2ee877327fded2c2b1978453831c2b1b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2ee877327fded2c2b1978453831c2b1b">&#9670;&nbsp;</a></span>Mdt_builder_ptr</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Mdt_builder_ptr =  shared_ptr&lt;<a class="el" href="classipc_1_1session_1_1Session.html#ac3f52804db8ecf1d0dc0d0bbdf97e062">Mdt_builder</a>&gt;</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Ref-counted handle to a capnp-generated <code>Builder</code> (and the payload it accesses) through which the user shall mutate the <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> metadata before invoking <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>. </p>
<p ><a class="el" href="classipc_1_1session_1_1Session.html#a420df732069ded1feef423adf7a30915" title="Returns a new metadata holder to be subsequently mutated by the user and then passed to open_channel(...">mdt_builder()</a> returns a new one; then user mutates it; then user calls <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>. To mutate an <code>x</code> of this type: <code>auto root = x-&gt;initPayload();</code>, then mutate via the <code>root</code> sub-builder (standard capnp-generated API for whatever fields capnp-<code>struct</code> <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b" title="Short-hand for Mdt_payload template arg.">Mdt_payload_obj</a> defines). </p>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00251">251</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="af572e522f2e85258bdfd091fd6e9a58b" name="af572e522f2e85258bdfd091fd6e9a58b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#af572e522f2e85258bdfd091fd6e9a58b">&#9670;&nbsp;</a></span>Mdt_payload_obj</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Mdt_payload_obj =  Mdt_payload</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Short-hand for <code>Mdt_payload</code> template arg. </p>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00238">238</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="ae197d051e06be6f132e193e9ba7ab6ae" name="ae197d051e06be6f132e193e9ba7ab6ae"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae197d051e06be6f132e193e9ba7ab6ae">&#9670;&nbsp;</a></span>Mdt_reader_ptr</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Mdt_reader_ptr =  shared_ptr&lt;typename transport::struc::schema::Metadata&lt;<a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b">Mdt_payload_obj</a>&gt;::Reader&gt;</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Ref-counted handle to a capnp-generated <code>Reader</code> (and the payload it accesses) through which the user shall access the metadata the other side prepared via <a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b" title="Ref-counted handle to a capnp-generated Builder (and the payload it accesses) through which the user ...">Mdt_builder_ptr</a>. </p>
<p >On-passive-open handler yields a handle of this type. To access via an <code>x</code> of this type: <code>auto root = x-&gt;getPayload();</code>, then access via the <code>root</code> sub-reader (standard capnp-generated API for whatever fields capnp-<code>struct</code> <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b" title="Short-hand for Mdt_payload template arg.">Mdt_payload_obj</a> defines). </p>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00261">261</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="a29eaaa691a992e3a83662e00be7d7446" name="a29eaaa691a992e3a83662e00be7d7446"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a29eaaa691a992e3a83662e00be7d7446">&#9670;&nbsp;</a></span>Structured_channel</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
<div class="memtemplate">
template&lt;typename Message_body &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Structured_channel =  <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html">transport::struc::Channel</a>&lt;unspecified&gt;</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Convenience alias for the <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a> concrete type to use if one desires (1) to upgrade a <code>*this</code>-generated channel to a <code>struc::Channel</code> and (2) to efficiently use the built-in capabilities of <code>*this</code> (notably, if applicable: SHM) for zero-copy performance when sending messages through that channel. </p>
<dl class="section note"><dt>Note</dt><dd>This alias is to an async-I/O <code>struc::Channel</code>. (See <a class="el" href="namespaceipc_1_1util_1_1sync__io.html" title="Contains common code, as well as important explanatory documentation in the following text,...">util::sync_io</a> doc header for background on the 2 patterns, async-I/O and <code><a class="el" href="namespaceipc_1_1session_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::session.">sync_io</a></code>.) To obtain the <code><a class="el" href="namespaceipc_1_1session_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::session.">sync_io</a></code>-core counterpart type use: <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9426e8e562dd4c9ea1bc1f69f47bb99f" title="Useful for generic programming, the sync_io-pattern counterpart to *this type.">Session::Structured_channel::Sync_io_obj</a></code>.</dd></dl>
<h3>Informal suggestion</h3>
<p >Use this (parameterized by <code>Message_body</code> of choice of course) as your <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a> concrete type. Then use the appropriate tag-form <code>struc::Channel</code> ctor. Namely as of this writing:</p><ul>
<li><code>*_shm_*_session</code>: Use tag <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel__base.html#af732121649271d1368a2fb637917ce7b" title="The sole value of the tag type Serialize_via_app_shm.">transport::struc::Channel_base::S_SERIALIZE_VIA_APP_SHM</a> or <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel__base.html#a9bdb94c1ba4fac92fbbd0f843e8525ba" title="The sole value of the tag type Serialize_via_session_shm.">transport::struc::Channel_base::S_SERIALIZE_VIA_SESSION_SHM</a></li>
<li>Non-shm <code>*_session</code>: Use tag <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel__base.html#ab0eb05b5fb52364c99868a8535aaf26e" title="The sole value of the tag type Serialize_via_heap.">transport::struc::Channel_base::S_SERIALIZE_VIA_HEAP</a>.</li>
</ul>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">Message_body</td><td>See <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a>. All the other annoying decisions are made for you using this alias; but of course you must still specify the language you shall be speaking over the channel. </td></tr>
  </table>
  </dd>
</dl>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00288">288</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="a2612cefeace1ba12e649ba0e509aaab1" name="a2612cefeace1ba12e649ba0e509aaab1"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2612cefeace1ba12e649ba0e509aaab1">&#9670;&nbsp;</a></span>Structured_msg_builder_config</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Structured_msg_builder_config =  unspecified</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Convenience alias equal to <code>Structured_channel&lt;M&gt;::Builder_config</code> (regardless of <code>M</code>). </p>
<p >See <a class="el" href="classipc_1_1session_1_1Session.html#a29eaaa691a992e3a83662e00be7d7446" title="Convenience alias for the transport::struc::Channel concrete type to use if one desires (1) to upgrad...">Structured_channel</a>.</p>
<p >Informally: The impl template may choose to provide methods to obtain a <a class="el" href="classipc_1_1session_1_1Session.html#a2612cefeace1ba12e649ba0e509aaab1" title="Convenience alias equal to Structured_channel&lt;M&gt;::Builder_config (regardless of M).">Structured_msg_builder_config</a> to use for a <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#a860cc99a701576879ebb5a1db58153cc" title="Encapsulation of any out-message payload sent or meant to be sent via send() (et al) by a *this of th...">Structured_channel::Msg_out</a></code> that can be constructed without a concrete <a class="el" href="classipc_1_1session_1_1Session.html#a29eaaa691a992e3a83662e00be7d7446" title="Convenience alias for the transport::struc::Channel concrete type to use if one desires (1) to upgrad...">Structured_channel</a> available. These methods might in some cases even be <code>static</code> (in which case they should take a <code>Logger* logger_ptr</code> 1st arg), so that not even having a <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> object in hand is needed. </p>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00300">300</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="ac23d047087984addf221f0baa0058616" name="ac23d047087984addf221f0baa0058616"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac23d047087984addf221f0baa0058616">&#9670;&nbsp;</a></span>Structured_msg_reader_config</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Structured_msg_reader_config =  unspecified</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Convenience alias equal to <code>Structured_channel&lt;M&gt;::Reader_config</code> (regardless of <code>M</code>). </p>
<p >See <a class="el" href="classipc_1_1session_1_1Session.html#a29eaaa691a992e3a83662e00be7d7446" title="Convenience alias for the transport::struc::Channel concrete type to use if one desires (1) to upgrad...">Structured_channel</a>. The utility of explicit use of this alias by the user is less than <a class="el" href="classipc_1_1session_1_1Session.html#a2612cefeace1ba12e649ba0e509aaab1" title="Convenience alias equal to Structured_channel&lt;M&gt;::Builder_config (regardless of M).">Structured_msg_builder_config</a>, as a <a class="el" href="classipc_1_1transport_1_1struc_1_1Msg__in.html" title="A structured in-message instance suitable as received and emittable (to user) by struc::Channel.">transport::struc::Msg_in</a> is not constructed directly but by <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a> internals. </p>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00308">308</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="a08416c5a34aa4eb58db094e946b540e3" name="a08416c5a34aa4eb58db094e946b540e3"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a08416c5a34aa4eb58db094e946b540e3">&#9670;&nbsp;</a></span>Session() <span class="overload">[1/2]</span></h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Session </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Default ctor: creates <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> in NULL state (not operational). </p>
<p >Beyond this and the move ctor, other ctors are unspecified by the concept but may well exist. See discussion in concept doc header.</p>
<p >The practical intended use for this ctor is as a target for a subsequent move-to assignment. For example, <a class="el" href="classipc_1_1session_1_1Session__server.html#a13887cd64912bb5f5675e2817ff8435f" title="Asynchronously awaits for an opposing Client_session to request session establishment and calls on_do...">Session_server::async_accept()</a> would typically be given a default-cted Server_session which, on success, is moved-to to enter PEER state. </p>

</div>
</div>
<a id="a230afdc0889f869e3b0606a826115745" name="a230afdc0889f869e3b0606a826115745"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a230afdc0889f869e3b0606a826115745">&#9670;&nbsp;</a></span>Session() <span class="overload">[2/2]</span></h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::Session </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1session_1_1Session.html">Session</a>&lt; Mdt_payload &gt; &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move ctor: <code>*this</code> becomes identical to <code>src</code>; while <code>src</code> becomes as-if default-cted. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Moved-from session that enters NULL state. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="a8cb20f446c2a4327a3a8143af137dbca" name="a8cb20f446c2a4327a3a8143af137dbca"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8cb20f446c2a4327a3a8143af137dbca">&#9670;&nbsp;</a></span>~Session()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::~<a class="el" href="classipc_1_1session_1_1Session.html">Session</a> </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In NULL state, no-op; in PEER state: Ends the session while informing (if possible) the opposing peer <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> that the present session has ended. </p>
<p >This may incur a short delay before the dtor exits (in practice likely to flush out any pending sends over an internal session master channel, informally speaking).</p>
<p >Any <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a> previously yielded by <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> and/or passive-opens shall continue operating, if still operating, and it is up to the user to perform any cleanup/flushing/etc. on these. This is consistent with the idea that <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> and passive-open passes ownership of such channels to the user.</p>
<p >There are 2 mutually exclusive expected triggers for why this dtor would be invoked:</p><ul>
<li>The present process is exiting gracefully (hence the session must end). User invokes dtor. Dtor informs the other side with maximum expediency; then returns.</li>
<li>The opposing process is exiting gracefully or otherwise; the opposing <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> thus informed ours gracefully or otherwise; therefore <code>*this</code> informs user of this via emitted error (see concept doc header regarding session-hosing error emission semantics); therefore <code>*this</code> is no longer usable; hence user invokes <code>*this</code> dtor. It tries to inform the other side, but there's nothing to inform; it quickly returns. </li>
</ul>

</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a id="a420df732069ded1feef423adf7a30915" name="a420df732069ded1feef423adf7a30915"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a420df732069ded1feef423adf7a30915">&#9670;&nbsp;</a></span>mdt_builder()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b">Mdt_builder_ptr</a> <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::mdt_builder </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Returns a new metadata holder to be subsequently mutated by the user and then passed to <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> to initiate active-open attempt. </p>
<p >The payload (see <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b" title="Short-hand for Mdt_payload template arg.">Mdt_payload_obj</a>) is left uninitialized: the user would likely <code>x-&gt;initPayload()</code> and then mutate stuff inside that (where <code>x</code> was returned).</p>
<p >If <code>*this</code> is not in PEER state, returns null.</p>
<p >This call is not needed, if one plans to use <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> overload that takes no metadata.</p>
<dl class="section return"><dt>Returns</dt><dd>See above. </dd></dl>

</div>
</div>
<a id="aab01aefa0243abf84c7cc36d3ab2d852" name="aab01aefa0243abf84c7cc36d3ab2d852"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aab01aefa0243abf84c7cc36d3ab2d852">&#9670;&nbsp;</a></span>open_channel() <span class="overload">[1/2]</span></h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">bool <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::open_channel </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">Channel_obj</a> *&#160;</td>
          <td class="paramname"><em>target_channel</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="classipc_1_1session_1_1Session.html#a2ee877327fded2c2b1978453831c2b1b">Mdt_builder_ptr</a> &amp;&#160;</td>
          <td class="paramname"><em>mdt</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Synchronously active-opens a new channel which, on success, is moved-to <code>*target_channel</code>. </p>
<p >No-op and return <code>false</code> if <code>*this</code> is not in PEER state, the session is hosed by a previous error, or <code>mdt</code> is null. Else returns <code>true</code>.</p>
<p ><code>mdt</code> shall be from an <a class="el" href="classipc_1_1session_1_1Session.html#a420df732069ded1feef423adf7a30915" title="Returns a new metadata holder to be subsequently mutated by the user and then passed to open_channel(...">mdt_builder()</a> call, and <code>mdt</code> must not have been passed to <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> previously; otherwise behavior undefined. See also the <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> overload that takes no <code>mdt</code>.</p>
<dl class="section note"><dt>Note</dt><dd>This is a compile-time fact, but we point it out just the same: <code>*target_channel</code> is of a <code><a class="el" href="namespaceipc_1_1session_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::session.">sync_io</a></code>-core-bearing type. However, on successful <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> you can trivially obtain an async-I/O version via <code>target_channel-&gt;async_io_obj()</code>.</dd></dl>
<h3>Is it blocking or non-blocking?</h3>
<p >That's a matter of perspective; but formally it must be either non-blocking or, if blocking, then limited to a timeout no greater than seconds (not minutes). That said, informally, the implementation shall strive to make this quite fast, enough so to be considered non-blocking, <em>as long as both <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> objects are in PEER state</em>.</p>
<h3>Error emission</h3>
<p >If <code>false</code> is returned, even if <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> internally triggered a session-hosing condition, it shall be fired through the on-error handler and not emitted by <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>.</p>
<p >If <code>true</code> is returned an error may be detected and is then emitted via standard Flow semantics (if <code>err_code</code> then set <code>*err_code</code> to error; otherwise throw). Such an error is <em>not</em> session-hosing.</p>
<p >In particular if passive-opens are disabled on the opposing side it must emit <a class="el" href="namespaceipc_1_1session_1_1error.html#a0708d4bec9ae853f4d7e3d7822fc8f2fa2c8c27c65ff6234220a84f96de8a1870" title="Session channel opening: User code chose to reject all passive-open requests.">error::Code::S_SESSION_OPEN_CHANNEL_REMOTE_PEER_REJECTED_PASSIVE_OPEN</a>. Informally: an impl is likely to be capable of emitting the non-fatal <a class="el" href="namespaceipc_1_1session_1_1error.html#a0708d4bec9ae853f4d7e3d7822fc8f2fa7d85b87223a9b277b8875c1f7971d6ad" title="Session channel opening: Other peer must reply quickly enough as-if non-blocking but did not do so in...">error::Code::S_SESSION_OPEN_CHANNEL_ACTIVE_TIMEOUT</a>, though the user is reasonably likely to want to treat it as fatal in practice and end the session.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">target_channel</td><td>On success <code>*target_channel</code> is moved-to from a (new) <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a> in PEER state. </td></tr>
    <tr><td class="paramname">mdt</td><td>See <a class="el" href="classipc_1_1session_1_1Session.html#a420df732069ded1feef423adf7a30915" title="Returns a new metadata holder to be subsequently mutated by the user and then passed to open_channel(...">mdt_builder()</a>. If <code>mdt</code> is null, <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> returns <code>false</code>. </td></tr>
    <tr><td class="paramname">err_code</td><td>See <code>flow::Error_code</code> docs for error reporting semantics. <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> generated: <a class="el" href="namespaceipc_1_1session_1_1error.html#a0708d4bec9ae853f4d7e3d7822fc8f2fa2c8c27c65ff6234220a84f96de8a1870" title="Session channel opening: User code chose to reject all passive-open requests.">error::Code::S_SESSION_OPEN_CHANNEL_REMOTE_PEER_REJECTED_PASSIVE_OPEN</a>, other possible unspecified errors according to impl's discretion. See above discussion. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>See above. </dd></dl>

</div>
</div>
<a id="afd8c8f5e2c71c2c4c58f77f134aa076c" name="afd8c8f5e2c71c2c4c58f77f134aa076c"></a>
<h2 class="memtitle"><span class="permalink"><a href="#afd8c8f5e2c71c2c4c58f77f134aa076c">&#9670;&nbsp;</a></span>open_channel() <span class="overload">[2/2]</span></h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">bool <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::open_channel </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2">Channel_obj</a> *&#160;</td>
          <td class="paramname"><em>target_channel</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Identical to <code>open_channel(target_channel, mdt_builder(), err_code)</code>; in other words attempts to open channel with an uninitialized channel-open metadata payload. </p>
<p >Informally: this overload can be used if differentiation among channels, for the passive-open side's benefit, is not necessary. In that case <a class="el" href="classipc_1_1session_1_1Session.html#af572e522f2e85258bdfd091fd6e9a58b" title="Short-hand for Mdt_payload template arg.">Mdt_payload_obj</a> is typically set to <code>capnp::Void</code>.</p>
<dl class="section note"><dt>Note</dt><dd>This is a compile-time fact, but we point it out just the same: <code>*target_channel</code> is of a <code><a class="el" href="namespaceipc_1_1session_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::session.">sync_io</a></code>-core-bearing type. However, on successful <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> you can trivially obtain an async-I/O version via <code>target_channel-&gt;async_io_obj()</code>.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">target_channel</td><td>See other <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>. </td></tr>
    <tr><td class="paramname">err_code</td><td>See other <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>See other <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a>. However it cannot return <code>false</code> due to an empty <code>mdt</code>, as <code>mdt</code> is internally generated (and left uninitialized). </dd></dl>

</div>
</div>
<a id="aa3e921f8f06a051423c60ba2f2736dde" name="aa3e921f8f06a051423c60ba2f2736dde"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa3e921f8f06a051423c60ba2f2736dde">&#9670;&nbsp;</a></span>operator=()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1session_1_1Session.html">Session</a> &amp; <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::operator= </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1session_1_1Session.html">Session</a>&lt; Mdt_payload &gt; &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move assignment: acts as-if <code>*this</code> dtor executed; then <code>*this</code> becomes identical to <code>src</code>; while <code>src</code> becomes as-if default-cted. </p>
<p >No-op if <code>&amp;src == this</code>.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Moved-from session that enters NULL state (unless <code>&amp;src == this</code>). </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>*this</code>. </dd></dl>

</div>
</div>
<a id="abc6ce8839621c1e19db80ccd4f2e2589" name="abc6ce8839621c1e19db80ccd4f2e2589"></a>
<h2 class="memtitle"><span class="permalink"><a href="#abc6ce8839621c1e19db80ccd4f2e2589">&#9670;&nbsp;</a></span>session_token()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">const <a class="el" href="namespaceipc_1_1session.html#ade2b302f1a3623e8adc9694568d94d2c">Session_token</a> &amp; <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::session_token </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td> const</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In PEER state: Returns the (non-nil) logged-in session token to be used for any <code>struc::Channel</code>s one may wish to upgrade from <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a> channels yielded by <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> or passive-opens; or nil if in NULL state, or if <code>*this</code> session is hosed from a prior error. </p>
<p >Informal context: Firstly see <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#a9a540a274df3bc7da8fc35ed2a2c1e57" title="Returns the (non-nil) logged-in session token; or nil if not in logged-in phase, or if a prior error ...">transport::struc::Channel::session_token()</a> and class template doc header. However note that <a class="el" href="classipc_1_1session_1_1Session.html#aab01aefa0243abf84c7cc36d3ab2d852" title="Synchronously active-opens a new channel which, on success, is moved-to *target_channel.">open_channel()</a> (active-open) and on-passive-open handler yields an unstructured, unused <a class="el" href="classipc_1_1session_1_1Session.html#a2f770785552536f3b929f293c44834d2" title="Each successful open_channel() and on-passive-open handler firing shall yield a concrete transport::C...">Channel_obj</a>: it is entirely optional that the user then upgrade it to a <code>struc::Channel</code>. <em>If</em> one does so, however, then a non-nil session-token shall be <em>required</em> and, for safety, must equal what this <a class="el" href="classipc_1_1session_1_1Session.html#abc6ce8839621c1e19db80ccd4f2e2589" title="In PEER state: Returns the (non-nil) logged-in session token to be used for any struc::Channels one m...">session_token()</a> returns.</p>
<dl class="section return"><dt>Returns</dt><dd>See above. The reference returned shall always be one of 2: a certain unspecified internal item, or to <a class="el" href="namespaceipc_1_1transport_1_1struc.html#ad556d20a2aa2d52b83c7afb73951d47d" title="A value for which .is_nil() is true.">transport::struc::NULL_SESSION_TOKEN</a>. </dd></dl>

</div>
</div>
<h2 class="groupheader">Member Data Documentation</h2>
<a id="a7f28ff5d2fc6e9830877979fafe48cf7" name="a7f28ff5d2fc6e9830877979fafe48cf7"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a7f28ff5d2fc6e9830877979fafe48cf7">&#9670;&nbsp;</a></span>S_SHM_ENABLED</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">constexpr bool <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::S_SHM_ENABLED = unspecified</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span><span class="mlabel">constexpr</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Specifies whether this <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> concept implementation provides support for zero-copy via SHM plus direct access to SHM arenas and lending/borrowing within them. </p>
<p >May be useful for generic programming; perhaps in <code>std::conditional</code> or <code>if constexpr()</code> uses.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1session_1_1Session.html#a62a1a415a92bf6e0b4d83987394ae78b" title="Specifies the SHM-provider for which this Session concept implementation provides support; or NONE if...">S_SHM_TYPE</a> </dd></dl>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00329">329</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<a id="a62a1a415a92bf6e0b4d83987394ae78b" name="a62a1a415a92bf6e0b4d83987394ae78b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a62a1a415a92bf6e0b4d83987394ae78b">&#9670;&nbsp;</a></span>S_SHM_TYPE</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Mdt_payload  = ::capnp::Void&gt; </div>
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">constexpr schema::ShmType <a class="el" href="classipc_1_1session_1_1Session.html">ipc::session::Session</a>&lt; Mdt_payload &gt;::S_SHM_TYPE = unspecified</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span><span class="mlabel">constexpr</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Specifies the SHM-provider for which this <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> concept implementation provides support; or <code>NONE</code> if this is a vanilla <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> that does not provide SHM-based zero-copy support. </p>
<p >May be useful for generic programming; perhaps in <code>std::conditional</code> or <code>if constexpr()</code> uses. Informally we recommend against frequent use of this except logging/reporting/alerting and debug/test scenarios.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1session_1_1Session.html#a7f28ff5d2fc6e9830877979fafe48cf7" title="Specifies whether this Session concept implementation provides support for zero-copy via SHM plus dir...">S_SHM_ENABLED</a>. </dd></dl>

<p class="definition">Definition at line <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html#l00320">320</a> of file <a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a>.</p>

</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li>session/<a class="el" href="ipc__session_2src_2ipc_2session_2session_8hpp_source.html">session.hpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 11 2025 20:02:26 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
